<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Function Description: Evaluator > -->
<div class='chapter' id='5'>5. Evaluation</div><p class='cindent'><!-- "evaluation" -->

	The following is a complete description of the actions taken by the
evaluator, given a <!-- open: 1, close: 0 --><font class="italic">form</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED --> to evaluate.

	If <!-- open: 2, close: 1 --><font class="italic">form</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED --> is a number, the result is <!-- open: 3, close: 2 --><font class="italic">form</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED -->.

	If <!-- open: 4, close: 3 --><font class="italic">form</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED --> is a string, the result is <!-- open: 5, close: 4 --><font class="italic">form</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED -->.

	If <!-- open: 6, close: 5 --><font class="italic">form</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED --> is a symbol, the result is the binding
of <!-- open: 7, close: 6 --><font class="italic">form</font><!-- open: 7, close: 7 --> <!-- MATCHED MATCHED MATCHED -->.  If <!-- open: 8, close: 7 --><font class="italic">form</font><!-- open: 8, close: 8 --> <!-- MATCHED MATCHED MATCHED --> is unbound, an error is signalled.

	If <!-- open: 9, close: 8 --><font class="italic">form</font><!-- open: 9, close: 9 --> <!-- MATCHED MATCHED MATCHED --> is not any of the above types, and is not a list,
an error is signalled.

	If <!-- open: 10, close: 9 --><font class="italic">form</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED --> is a special form, indentified by a distinguished
symbol as its car, it is handled accordingly; each special form works
differently.  All of them are documented in this manual.

	If <!-- open: 11, close: 10 --><font class="italic">form</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED --> is not a special form, it calls for the <!-- open: 12, close: 11 --><font class="italic">application</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED -->
of a function to <!-- open: 13, close: 12 --><font class="italic">arguments</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED -->.  The <!-- open: 14, close: 13 --><font class="italic">car</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED --> of the form is a function or
the name of a function.  The <!-- open: 15, close: 14 --><font class="italic">cdr</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED --> of the form is a list of forms which
are evaluated to produce arguments, which are fed to the function.  Whatever
results the function <!-- open: 16, close: 15 --><font class="italic">returns</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED --> is the value of the original <!-- open: 17, close: 16 --><font class="italic">form</font><!-- open: 17, close: 17 --> <!-- MATCHED MATCHED MATCHED -->.

<!-- Someone should do this but I don't want to do it right now. -->
[Here there should be the rest of the moby description of evaluation and application,
particularly multiple values.  Explain the term "variables", also a very
brief bit about locals and specials (fluids and lexicals??).
The nature of functions should be revealed;
including compiled-code, interpreted-code, arrays, stacks, closures,
symbols.  Discuss macros.
Talk about function-calling in compiled code, how this is essentially
identical to the <!-- open: 18, close: 17 --><font class="lisp">apply</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED --> function, and no need for <!-- open: 19, close: 18 --><font class="lisp">(sstatus uuolinks)</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED -->
and the like.]

<div class='section' id='5.1'>5.1 Functions and Special Forms</div>
<div class='defun' id='eval'>
  <font class='exdent'>
    <font class='funcname'>eval </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
<!-- open: 20, close: 19 --><font class="lisp">(eval <!-- open: 21, close: 19 --><font class="italic">x</font><!-- open: 21, close: 20 -->)</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED --> evaluates <!-- open: 22, close: 21 --><font class="italic">x</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED -->, and returns the result.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(setq x 43 foo 'bar)
(eval (list 'cons x 'foo))
    =&gt; (43 . bar)
</pre>
	It is unusual to explicitly call <!-- open: 23, close: 22 --><font class="lisp">eval</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED -->, since usually
evaluation is done implicitly.  If you are writing a simple Lisp program and
explicitly calling <!-- open: 24, close: 23 --><font class="lisp">eval</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED -->, you are probably doing something wrong.
<!-- open: 25, close: 24 --><font class="lisp">eval</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED --> is primarily useful in programs which deal with Lisp itself,
rather than programs about knowledge or mathematics or games.
	Also, if you are only interested in getting at the value of a
symbol (that is, the contents of the symbol's value cell), then you
should use the primitive function <!-- open: 26, close: 25 --><font class="lisp">symeval</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED -->.
'findex "symeval"
	Note: the actual name of the compiled code for <!-- open: 27, close: 26 --><font class="lisp">eval</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED --> is "<!-- open: 28, close: 27 --><font class="lisp">si:*eval</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED -->";
this is because use of the <!-- open: 29, close: 28 --><font class="italic">evalhook</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED --> feature binds the function cell of <!-- open: 30, close: 29 --><font class="lisp">eval</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED -->.
If you don't understand this, you can safely ignore it.
<p class='cindent'><!-- "evalhook" -->
'findex "evalhook"
	Note: unlike Maclisp, <!-- open: 31, close: 30 --><font class="lisp">eval</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED --> never takes a second argument; there
are no "binding context pointers" in Lisp Machine Lisp.
They are replaced by Closures (see <font color='red'>LINK:(</font>closure)).
</div>

<div class='defun' id='apply'>
  <font class='exdent'>
    <font class='funcname'>apply </font>
    <font class='italic' color='purple'>fn arglist</font>
  </font><br>
<!-- open: 32, close: 31 --><font class="lisp">(apply <!-- open: 33, close: 31 --><font class="italic">fn arglist</font><!-- open: 33, close: 32 -->)</font><!-- open: 33, close: 33 --> <!-- MATCHED MATCHED MATCHED --> applies the function <!-- open: 34, close: 33 --><font class="italic">fn</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED --> to the list of
arguments <!-- open: 35, close: 34 --><font class="italic">arglist</font><!-- open: 35, close: 35 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 36, close: 35 --><font class="italic">arglist</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED --> should be a list; <!-- open: 37, close: 36 --><font class="italic">fn</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED --> can be a
compiled-code object, or a "lambda expression", i.e., a list whose <!-- open: 38, close: 37 --><font class="lisp">car</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED -->
is the symbol <!-- open: 39, close: 38 --><font class="lisp">lambda</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED -->, or a symbol, in which case its definition (the contents
of its function cell) is used.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(setq f '+) (apply f '(1 2)) =&gt; 3
(setq f '-) (apply f '(1 2)) =&gt; -1
(apply 'cons '((+ 2 3) 4)) =&gt;
		((+ 2 3) . 4)	<!-- open: 40, close: 39 --><font class="italic">not</font><!-- open: 40, close: 40 --> <!-- MATCHED MATCHED MATCHED --> (5 . 4)
</pre>
	Of course, <!-- open: 41, close: 40 --><font class="italic">arglist</font><!-- open: 41, close: 41 --> <!-- MATCHED MATCHED MATCHED --> may be <!-- open: 42, close: 41 --><font class="lisp">nil</font><!-- open: 42, close: 42 --> <!-- MATCHED MATCHED MATCHED -->.
	Note: unlike Maclisp, <!-- open: 43, close: 42 --><font class="lisp">apply</font><!-- open: 43, close: 43 --> <!-- MATCHED MATCHED MATCHED --> never takes a third argument; there
are no "binding context pointers" in Lisp Machine Lisp.

	Compare <!-- open: 44, close: 43 --><font class="lisp">apply</font><!-- open: 44, close: 44 --> <!-- MATCHED MATCHED MATCHED --> with <!-- open: 45, close: 44 --><font class="lisp">funcall</font><!-- open: 45, close: 45 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 46, close: 45 --><font class="lisp">eval</font><!-- open: 46, close: 46 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='funcall'>
  <font class='exdent'>
    <font class='funcname'>funcall </font>
    <font class='italic' color='purple'>f &rest args</font>
  </font><br>
<!-- open: 47, close: 46 --><font class="lisp">(funcall <!-- open: 48, close: 46 --><font class="italic">f a1 a2 ... an</font><!-- open: 48, close: 47 -->)</font><!-- open: 48, close: 48 --> <!-- MATCHED MATCHED MATCHED --> applies the function <!-- open: 49, close: 48 --><font class="italic">f</font><!-- open: 49, close: 49 --> <!-- MATCHED MATCHED MATCHED --> to the arguments
<!-- open: 50, close: 49 --><font class="italic">a1, a2, ..., an</font><!-- open: 50, close: 50 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 51, close: 50 --><font class="lisp">f</font><!-- open: 51, close: 51 --> <!-- MATCHED MATCHED MATCHED --> may not
be a special form nor a macro; this would not be meaningful.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(cons 1 2) =&gt; (1 . 2)
(setq cons 'plus)
(funcall cons 1 2) =&gt; 3
</pre>
</div>

<div class='defun' id='lexpr-funcall'>
  <font class='exdent'>
    <font class='funcname'>lexpr-funcall </font>
    <font class='italic' color='purple'>f &rest args</font>
  </font><br>
<!-- open: 52, close: 51 --><font class="lisp">lexpr-funcall</font><!-- open: 52, close: 52 --> <!-- MATCHED MATCHED MATCHED --> is like a cross between <!-- open: 53, close: 52 --><font class="lisp">apply</font><!-- open: 53, close: 53 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 54, close: 53 --><font class="lisp">funcall</font><!-- open: 54, close: 54 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 55, close: 54 --><font class="lisp">(lexpr-funcall <!-- open: 56, close: 54 --><font class="italic">f a1 a2 ... an list</font><!-- open: 56, close: 55 -->)</font><!-- open: 56, close: 56 --> <!-- MATCHED MATCHED MATCHED --> applies the function <!-- open: 57, close: 56 --><font class="italic">f</font><!-- open: 57, close: 57 --> <!-- MATCHED MATCHED MATCHED -->
to the arguments <!-- open: 58, close: 57 --><font class="italic">a1</font><!-- open: 58, close: 58 --> <!-- MATCHED MATCHED MATCHED --> through <!-- open: 59, close: 58 --><font class="italic">an</font><!-- open: 59, close: 59 --> <!-- MATCHED MATCHED MATCHED --> followed by the elements of
<!-- open: 60, close: 59 --><font class="italic">list</font><!-- open: 60, close: 60 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(lexpr-funcall 'plus 1 1 1 '(1 1 1)) =&gt; 6

(defun report-error (&amp;rest args)
   (lexpr-funcall (function format) error-output args))
</pre>
</div>

Note:  the Maclisp functions <!-- open: 61, close: 60 --><font class="lisp">subrcall</font><!-- open: 61, close: 61 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 62, close: 61 --><font class="lisp">lsubrcall</font><!-- open: 62, close: 62 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 63, close: 62 --><font class="lisp">arraycall</font><!-- open: 63, close: 63 --> <!-- MATCHED MATCHED MATCHED -->
are not needed on the Lisp Machine; <!-- open: 64, close: 63 --><font class="lisp">funcall</font><!-- open: 64, close: 64 --> <!-- MATCHED MATCHED MATCHED --> is just as efficient.
<!-- Are these provided anyway, though? NO. -->
'findex "subrcall"
'findex "lsubrcall"
'findex "arraycall"

<div class='defspec' id='quote'><font class='exdent'><font class='funcname' id='quote'>quote</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><p class='cindent'><!-- "quote" -->
<!-- open: 65, close: 64 --><font class="lisp">(quote <!-- open: 66, close: 64 --><font class="italic">x</font><!-- open: 66, close: 65 -->)</font><!-- open: 66, close: 66 --> <!-- MATCHED MATCHED MATCHED --> simply returns <!-- open: 67, close: 66 --><font class="italic">x</font><!-- open: 67, close: 67 --> <!-- MATCHED MATCHED MATCHED -->.  It is useful because it takes the
argument <!-- open: 68, close: 67 --><font class="italic">quoted</font><!-- open: 68, close: 68 --> <!-- MATCHED MATCHED MATCHED -->, so that it is not evaluated by <!-- open: 69, close: 68 --><font class="lisp">eval</font><!-- open: 69, close: 69 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 70, close: 69 --><font class="lisp">quote</font><!-- open: 70, close: 70 --> <!-- MATCHED MATCHED MATCHED --> is used
to include constants in a form.
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(quote x) =&gt; x
(setq x (quote (some list)))   x =&gt; (some list)
</pre>
	Since <!-- open: 71, close: 70 --><font class="lisp">quote</font><!-- open: 71, close: 71 --> <!-- MATCHED MATCHED MATCHED --> is so useful but somewhat cumbersome to type, the reader normally
converts any form preceded by a single quote (&thinsp;<!-- open: 72, close: 71 --><font class="lisp">'</font><!-- open: 72, close: 72 --> <!-- MATCHED MATCHED MATCHED -->&thinsp;) character into a <!-- open: 73, close: 72 --><font class="lisp">quote</font><!-- open: 73, close: 73 --> <!-- MATCHED MATCHED MATCHED --> form.
<pre class='lisp'>
<!-- open: 74, close: 73 --><font class="main">For example,</font><!-- open: 74, close: 74 --> <!-- MATCHED MATCHED MATCHED -->
(setq x '(some list))
<!-- open: 75, close: 74 --><font class="main">is converted by read into</font><!-- open: 75, close: 75 --> <!-- MATCHED MATCHED MATCHED -->
(setq x (quote (some list)))
</pre>
</div>

<div class='defspec' id='function'><font class='exdent'><font class='funcname' id='function'>function</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 76, close: 75 --><font class="lisp">(function <!-- open: 77, close: 75 --><font class="italic">x</font><!-- open: 77, close: 76 -->)</font><!-- open: 77, close: 77 --> <!-- MATCHED MATCHED MATCHED --> is similar to <!-- open: 78, close: 77 --><font class="lisp">quote</font><!-- open: 78, close: 78 --> <!-- MATCHED MATCHED MATCHED -->, except that it implies
to the compiler that <!-- open: 79, close: 78 --><font class="italic">x</font><!-- open: 79, close: 79 --> <!-- MATCHED MATCHED MATCHED --> is a function.  In the interpreter, if <!-- open: 80, close: 79 --><font class="italic">x</font><!-- open: 80, close: 80 --> <!-- MATCHED MATCHED MATCHED --> is a symbol
<!-- open: 81, close: 80 --><font class="lisp">(function <!-- open: 82, close: 80 --><font class="italic">x</font><!-- open: 82, close: 81 -->)</font><!-- open: 82, close: 82 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 83, close: 82 --><font class="italic">x</font><!-- open: 83, close: 83 --> <!-- MATCHED MATCHED MATCHED -->'s definition;
otherwise <!-- open: 84, close: 83 --><font class="italic">x</font><!-- open: 84, close: 84 --> <!-- MATCHED MATCHED MATCHED --> itself is returned.
Because of this, using <!-- open: 85, close: 84 --><font class="lisp">function</font><!-- open: 85, close: 85 --> <!-- MATCHED MATCHED MATCHED --> rules out the possibility of later
changing the function definition of <!-- open: 86, close: 85 --><font class="italic">x</font><!-- open: 86, close: 86 --> <!-- MATCHED MATCHED MATCHED -->, including tracing it.  Care is required!
</div>

<div class='defspec' id='comment'><font class='exdent'><font class='funcname' id='comment'>comment</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 87, close: 86 --><font class="lisp">comment</font><!-- open: 87, close: 87 --> <!-- MATCHED MATCHED MATCHED --> ignores its form and returns the symbol <!-- open: 88, close: 87 --><font class="lisp">comment</font><!-- open: 88, close: 88 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(defun foo (x)
    (cond ((null x) 0)
          (t (comment x has something in it)
             (1+ (foo (cdr x))))))
</pre>
	Usually it is preferable to comment code using the
semicolon-macro feature of the standard input syntax.  This allows the
user to add comments to his code which are ignored by the lisp reader. 
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(defun foo (x)
    (cond ((null x) 0)
          (t (1+ (foo (cdr x))))     ;x has something in it
      ))
</pre>

A problem with such comments is that they are discarded when the S-expression
is read into lisp.  If the function is read into Lisp, modified, and printed
out again, the comment will be lost.  However, this style of operation is hardly
ever used; usually the source of a function is kept in an editor buffer and
any changes are made to the buffer, rather than the actual list structure
of the function.  Thus, this is not a real problem.
</div>

<div class='defmac' id='@define'><font class='exdent'><font class='funcname' id='@define'>@define</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->	This macro turns into <!-- open: 89, close: 88 --><font class="lisp">nil</font><!-- open: 89, close: 89 --> <!-- MATCHED MATCHED MATCHED -->.  It exists for the sake of the
@ listing generation program, which uses it to declare names of special forms
which define objects (such as functions) which @ should cross-reference.
</div>

<div class='defspec' id='progn'><font class='exdent'><font class='funcname' id='progn'>progn</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->A progn-form looks like <!-- open: 90, close: 89 --><font class="lisp">(progn <!-- open: 91, close: 89 --><font class="italic">form1 form2 ...</font><!-- open: 91, close: 90 -->)</font><!-- open: 91, close: 91 --> <!-- MATCHED MATCHED MATCHED -->.
The <!-- open: 92, close: 91 --><font class="italic">forms</font><!-- open: 92, close: 92 --> <!-- MATCHED MATCHED MATCHED --> are evaluated in order from left to right and the value
of the last one is the result of the progn. 
<!-- open: 93, close: 92 --><font class="lisp">progn</font><!-- open: 93, close: 93 --> <!-- MATCHED MATCHED MATCHED --> is the primitive control structure construct for "compound
statements".  Although lambda-expressions, cond-forms, do-forms, and
many other control structure forms use <!-- open: 94, close: 93 --><font class="lisp">progn</font><!-- open: 94, close: 94 --> <!-- MATCHED MATCHED MATCHED --> implicitly, that is,
they allow multiple forms in their bodies, there are occasions when
one needs to evaluate a number of forms for their side-effects and
make them appear to be a single form.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(foo (cdr a)
     (progn (setq b (extract frob))
	    (car b))
     (cadr b))
</pre>
</div>

<div class='defspec' id='prog1'><font class='exdent'><font class='funcname' id='prog1'>prog1</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 95, close: 94 --><font class="lisp">prog1</font><!-- open: 95, close: 95 --> <!-- MATCHED MATCHED MATCHED --> is similar to <!-- open: 96, close: 95 --><font class="lisp">progn</font><!-- open: 96, close: 96 --> <!-- MATCHED MATCHED MATCHED -->, but it returns the value of its <!-- open: 97, close: 96 --><font class="italic">first</font><!-- open: 97, close: 97 --> <!-- MATCHED MATCHED MATCHED --> form.
It is most commonly used to evaluate an expression with side effects, and return
a value which must be computed <!-- open: 98, close: 97 --><font class="italic">before</font><!-- open: 98, close: 98 --> <!-- MATCHED MATCHED MATCHED --> the side effects happen.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(setq x (prog1 y (setq y x)))
</pre>
which interchanges the values of the variables <!-- open: 99, close: 98 --><font class="italic">x</font><!-- open: 99, close: 99 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 100, close: 99 --><font class="italic">y</font><!-- open: 100, close: 100 --> <!-- MATCHED MATCHED MATCHED -->.

<!-- open: 101, close: 100 --><font class="lisp">prog1</font><!-- open: 101, close: 101 --> <!-- MATCHED MATCHED MATCHED --> could have been defined as:
<pre class='lisp'>
(defun prog1 (&amp;rest values)
    (car values))
</pre>
It is actually implemented as a macro which expands into a <!-- open: 102, close: 101 --><font class="lisp">prog2</font><!-- open: 102, close: 102 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defspec' id='prog2'><font class='exdent'><font class='funcname' id='prog2'>prog2</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 103, close: 102 --><font class="lisp">prog2</font><!-- open: 103, close: 103 --> <!-- MATCHED MATCHED MATCHED --> is similar to <!-- open: 104, close: 103 --><font class="lisp">progn</font><!-- open: 104, close: 104 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 105, close: 104 --><font class="lisp">prog1</font><!-- open: 105, close: 105 --> <!-- MATCHED MATCHED MATCHED -->,
but it returns its <!-- open: 106, close: 105 --><font class="italic">second</font><!-- open: 106, close: 106 --> <!-- MATCHED MATCHED MATCHED --> argument.
It is included largely for Maclisp compatibility.  It has two purposes: to evaluate
two forms sequentially, which can be done more generally with <!-- open: 107, close: 106 --><font class="lisp">progn</font><!-- open: 107, close: 107 --> <!-- MATCHED MATCHED MATCHED -->, or
to do what <!-- open: 108, close: 107 --><font class="lisp">prog1</font><!-- open: 108, close: 108 --> <!-- MATCHED MATCHED MATCHED --> is used for (c.f. <!-- open: 109, close: 108 --><font class="lisp">prog1</font><!-- open: 109, close: 109 --> <!-- MATCHED MATCHED MATCHED --> above).
</div>

<div class='defspec' id='let'><font class='exdent'><font class='funcname' id='let'>let</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 110, close: 109 --><font class="lisp">let</font><!-- open: 110, close: 110 --> <!-- MATCHED MATCHED MATCHED --> is used to bind some variables for some objects.
A <!-- open: 111, close: 110 --><font class="lisp">let</font><!-- open: 111, close: 111 --> <!-- MATCHED MATCHED MATCHED --> form looks like
<pre class='lisp'>
(let ((<!-- open: 112, close: 111 --><font class="italic">var1</font><!-- open: 112, close: 112 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 113, close: 112 --><font class="italic">vform1</font><!-- open: 113, close: 113 --> <!-- MATCHED MATCHED MATCHED -->)
      (<!-- open: 114, close: 113 --><font class="italic">var2</font><!-- open: 114, close: 114 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 115, close: 114 --><font class="italic">vform2</font><!-- open: 115, close: 115 --> <!-- MATCHED MATCHED MATCHED -->)
      ...)
  <!-- open: 116, close: 115 --><font class="italic">bform1</font><!-- open: 116, close: 116 --> <!-- MATCHED MATCHED MATCHED -->
  <!-- open: 117, close: 116 --><font class="italic">bform2</font><!-- open: 117, close: 117 --> <!-- MATCHED MATCHED MATCHED -->
  ...)
</pre>
When this form is evaluated, first the <!-- open: 118, close: 117 --><font class="italic">vform</font><!-- open: 118, close: 118 --> <!-- MATCHED MATCHED MATCHED -->s are evaluated.
Then the <!-- open: 119, close: 118 --><font class="italic">var</font><!-- open: 119, close: 119 --> <!-- MATCHED MATCHED MATCHED -->s are bound to the values returned by the
corresponding  <!-- open: 120, close: 119 --><font class="italic">vform</font><!-- open: 120, close: 120 --> <!-- MATCHED MATCHED MATCHED -->s.  Finally, the <!-- open: 121, close: 120 --><font class="italic">bform</font><!-- open: 121, close: 121 --> <!-- MATCHED MATCHED MATCHED -->s are evaluated sequentially
and the result of the last one returned.

<!-- open: 122, close: 121 --><font class="lisp">let</font><!-- open: 122, close: 122 --> <!-- MATCHED MATCHED MATCHED --> is implemented as a macro which expands into a lambda-combination;
however, it is preferable
to use <!-- open: 123, close: 122 --><font class="lisp">let</font><!-- open: 123, close: 123 --> <!-- MATCHED MATCHED MATCHED --> rather than <!-- open: 124, close: 123 --><font class="lisp">lambda</font><!-- open: 124, close: 124 --> <!-- MATCHED MATCHED MATCHED --> because the variables and the corresponding forms
appear textually close to each other, which increases readability
of the program.
</div>

See also <!-- open: 125, close: 124 --><font class="lisp">let-globally</font><!-- open: 125, close: 125 --> <!-- MATCHED MATCHED MATCHED -->, <font color='red'>LINK:(</font>let-globally-fun).

<div class='defspec' id='progv'><font class='exdent'><font class='funcname' id='progv'>progv</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 126, close: 125 --><font class="lisp">progv</font><!-- open: 126, close: 126 --> <!-- MATCHED MATCHED MATCHED --> is a special form to provide the user with extra control
over lambda-binding.  It binds a list of symbols to a list of values,
and then evaluates some forms.  The lists of symbols and values
are computed quantities; this is what makes <!-- open: 127, close: 126 --><font class="lisp">progv</font><!-- open: 127, close: 127 --> <!-- MATCHED MATCHED MATCHED --> different from
<!-- open: 128, close: 127 --><font class="lisp">lambda</font><!-- open: 128, close: 128 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 129, close: 128 --><font class="lisp">let</font><!-- open: 129, close: 129 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 130, close: 129 --><font class="lisp">prog</font><!-- open: 130, close: 130 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 131, close: 130 --><font class="lisp">do</font><!-- open: 131, close: 131 --> <!-- MATCHED MATCHED MATCHED -->.

<pre class='lisp'>
(progv <!-- open: 132, close: 131 --><font class="italic">symbol-list value-list form1 form2 </font><!-- open: 132, close: 132 --> <!-- MATCHED MATCHED MATCHED -->... )
</pre>
first evaluates <!-- open: 133, close: 132 --><font class="italic">symbol-list</font><!-- open: 133, close: 133 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 134, close: 133 --><font class="italic">value-list</font><!-- open: 134, close: 134 --> <!-- MATCHED MATCHED MATCHED -->.  Then the symbols
are bound to the values.  In compiled code the symbols must be <!-- open: 135, close: 134 --><font class="italic">special</font><!-- open: 135, close: 135 --> <!-- MATCHED MATCHED MATCHED -->,
since the compiler has no way of knowing what symbols might appear in the
<!-- open: 136, close: 135 --><font class="italic">symbol-list</font><!-- open: 136, close: 136 --> <!-- MATCHED MATCHED MATCHED -->.  If too few values are supplied, the remaining symbols
are bound to <!-- open: 137, close: 136 --><font class="lisp">nil</font><!-- open: 137, close: 137 --> <!-- MATCHED MATCHED MATCHED -->.  If too many values are supplied, the
excess values are ignored.

After the symbols have been bound to the values, the <!-- open: 138, close: 137 --><font class="italic">form</font><!-- open: 138, close: 138 --> <!-- MATCHED MATCHED MATCHED -->s are
evaluated, and finally the symbols' bindings are undone.
The result returned is the value of the last form.  Note that the
"body" of a <!-- open: 139, close: 138 --><font class="lisp">progv</font><!-- open: 139, close: 139 --> <!-- MATCHED MATCHED MATCHED --> is similar to that of <!-- open: 140, close: 139 --><font class="lisp">progn</font><!-- open: 140, close: 140 --> <!-- MATCHED MATCHED MATCHED -->, not that of <!-- open: 141, close: 140 --><font class="lisp">prog</font><!-- open: 141, close: 141 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(setq a 'foo b 'bar)

(progv (list a b 'b) (list b) (list a b foo bar))
    =&gt; (foo nil bar nil)
</pre>
During the evaluation of the body of this <!-- open: 142, close: 141 --><font class="lisp">progv</font><!-- open: 142, close: 142 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 143, close: 142 --><font class="lisp">foo</font><!-- open: 143, close: 143 --> <!-- MATCHED MATCHED MATCHED -->
is bound to <!-- open: 144, close: 143 --><font class="lisp">bar</font><!-- open: 144, close: 144 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 145, close: 144 --><font class="lisp">bar</font><!-- open: 145, close: 145 --> <!-- MATCHED MATCHED MATCHED --> is bound to <!-- open: 146, close: 145 --><font class="lisp">nil</font><!-- open: 146, close: 146 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 147, close: 146 --><font class="lisp">b</font><!-- open: 147, close: 147 --> <!-- MATCHED MATCHED MATCHED --> is
bound to <!-- open: 148, close: 147 --><font class="lisp">nil</font><!-- open: 148, close: 148 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 149, close: 148 --><font class="lisp">a</font><!-- open: 149, close: 149 --> <!-- MATCHED MATCHED MATCHED --> remains bound to <!-- open: 150, close: 149 --><font class="lisp">foo</font><!-- open: 150, close: 150 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

See also <!-- open: 151, close: 150 --><font class="lisp">bind</font><!-- open: 151, close: 151 --> <!-- MATCHED MATCHED MATCHED --> (see <font color='red'>LINK:(</font>bind-fun)), which is a
subprimitive which gives you maximal control over binding.

The following three functions (<!-- open: 152, close: 151 --><font class="lisp">arg</font><!-- open: 152, close: 152 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 153, close: 152 --><font class="lisp">setarg</font><!-- open: 153, close: 153 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 154, close: 153 --><font class="lisp">listify</font><!-- open: 154, close: 154 --> <!-- MATCHED MATCHED MATCHED -->)
exist only for compatibility with Maclisp <!-- open: 155, close: 154 --><font class="italic">lexprs</font><!-- open: 155, close: 155 --> <!-- MATCHED MATCHED MATCHED -->.
<p class='cindent'><!-- "lexpr" -->

<div class='defun' id='arg'>
  <font class='exdent'>
    <font class='funcname'>arg </font>
    <font class='italic' color='purple'>x</font>
  </font><br>
<!-- open: 156, close: 155 --><font class="lisp">(arg nil)</font><!-- open: 156, close: 156 --> <!-- MATCHED MATCHED MATCHED -->, when evaluated during the application of
a lexpr, gives the number of arguments supplied to that
lexpr.
This is primarily a debugging aid, since lexprs also receive their number of arguments
as the value of their <!-- open: 157, close: 156 --><font class="lisp">lambda</font><!-- open: 157, close: 157 --> <!-- MATCHED MATCHED MATCHED -->-variable.

<!-- open: 158, close: 157 --><font class="lisp">(arg <!-- open: 159, close: 157 --><font class="italic">i</font><!-- open: 159, close: 158 -->)</font><!-- open: 159, close: 159 --> <!-- MATCHED MATCHED MATCHED -->, when evaluated during the application of a lexpr, gives the value of the
<!-- open: 160, close: 159 --><font class="italic">i</font><!-- open: 160, close: 160 --> <!-- MATCHED MATCHED MATCHED -->'th argument to the lexpr.  <!-- open: 161, close: 160 --><font class="italic">i</font><!-- open: 161, close: 161 --> <!-- MATCHED MATCHED MATCHED --> must be a fixnum in this case. It is an error if <!-- open: 162, close: 161 --><font class="italic">i</font><!-- open: 162, close: 162 --> <!-- MATCHED MATCHED MATCHED --> is less than 1 or greater than the number
of arguments supplied to the lexpr.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(defun foo nargs            ;<!-- open: 163, close: 162 --><font class="main">define a lexpr </font><!-- open: 163, close: 163 --> <!-- MATCHED MATCHED MATCHED -->foo.
    (print (arg 2))         ;<!-- open: 164, close: 163 --><font class="main">print the second argument.</font><!-- open: 164, close: 164 --> <!-- MATCHED MATCHED MATCHED -->
    (+ (arg 1)              ;<!-- open: 165, close: 164 --><font class="main">return the sum of the first</font><!-- open: 165, close: 165 --> <!-- MATCHED MATCHED MATCHED -->
       (arg (- nargs 1))))  ;<!-- open: 166, close: 165 --><font class="main">and next to last arguments.</font><!-- open: 166, close: 166 --> <!-- MATCHED MATCHED MATCHED -->
</pre>
</div>

<div class='defun' id='setarg'>
  <font class='exdent'>
    <font class='funcname'>setarg </font>
    <font class='italic' color='purple'>i x</font>
  </font><br>
<!-- open: 167, close: 166 --><font class="lisp">setarg</font><!-- open: 167, close: 167 --> <!-- MATCHED MATCHED MATCHED --> is used only during the application of a lexpr.
<!-- open: 168, close: 167 --><font class="lisp">(setarg <!-- open: 169, close: 167 --><font class="italic">i x</font><!-- open: 169, close: 168 -->)</font><!-- open: 169, close: 169 --> <!-- MATCHED MATCHED MATCHED --> sets the
lexpr's <!-- open: 170, close: 169 --><font class="italic">i</font><!-- open: 170, close: 170 --> <!-- MATCHED MATCHED MATCHED -->'th argument to <!-- open: 171, close: 170 --><font class="italic">x</font><!-- open: 171, close: 171 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 172, close: 171 --><font class="italic">i</font><!-- open: 172, close: 172 --> <!-- MATCHED MATCHED MATCHED --> must be greater than zero
and not greater than the number of arguments passed to the lexpr.
After <!-- open: 173, close: 172 --><font class="lisp">(setarg <!-- open: 174, close: 172 --><font class="italic">i x</font><!-- open: 174, close: 173 -->)</font><!-- open: 174, close: 174 --> <!-- MATCHED MATCHED MATCHED --> has been done, <!-- open: 175, close: 174 --><font class="lisp">(arg <!-- open: 176, close: 174 --><font class="italic">i</font><!-- open: 176, close: 175 -->)</font><!-- open: 176, close: 176 --> <!-- MATCHED MATCHED MATCHED --> will return <!-- open: 177, close: 176 --><font class="italic">x</font><!-- open: 177, close: 177 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defun' id='listify'>
  <font class='exdent'>
    <font class='funcname'>listify </font>
    <font class='italic' color='purple'>n</font>
  </font><br>
<!-- open: 178, close: 177 --><font class="lisp">(listify <!-- open: 179, close: 177 --><font class="italic">n</font><!-- open: 179, close: 178 -->)</font><!-- open: 179, close: 179 --> <!-- MATCHED MATCHED MATCHED --> manufactures a list of <!-- open: 180, close: 179 --><font class="italic">n</font><!-- open: 180, close: 180 --> <!-- MATCHED MATCHED MATCHED --> of the
arguments of a lexpr.  With a positive argument <!-- open: 181, close: 180 --><font class="italic">n</font><!-- open: 181, close: 181 --> <!-- MATCHED MATCHED MATCHED -->, it returns a
list of the first <!-- open: 182, close: 181 --><font class="italic">n</font><!-- open: 182, close: 182 --> <!-- MATCHED MATCHED MATCHED --> arguments of the lexpr.  With a negative
argument <!-- open: 183, close: 182 --><font class="italic">n</font><!-- open: 183, close: 183 --> <!-- MATCHED MATCHED MATCHED -->, it returns a list of the last <!-- open: 184, close: 183 --><font class="lisp">(abs <!-- open: 185, close: 183 --><font class="italic">n</font><!-- open: 185, close: 184 -->)</font><!-- open: 185, close: 185 --> <!-- MATCHED MATCHED MATCHED -->
arguments of the lexpr.  Basically, it works as if defined as follows: 
<pre class='lisp'>
    (defun listify (n)
         (cond ((minusp n)
                (listify1 (arg nil) (+ (arg nil) n 1)))
               (t
                (listify1 n 1)) ))

    (defun listify1 (n m)      ;<!-- open: 186, close: 185 --><font class="main"> auxiliary function.</font><!-- open: 186, close: 186 --> <!-- MATCHED MATCHED MATCHED -->
         (do ((i n (1- i))
              (result nil (cons (arg i) result)))
             ((&lt; i m) result) ))
</pre>
</div>

<div class='section' id='5.2'>5.2 Functions and Special Forms</div>
The Lisp machine includes a facility by which the evaluation of a form
can produce more than one value.  When a function needs to return more
than one result to its caller, multiple values are a cleaner way of doing
this than returning a list of the values or <!-- open: 187, close: 186 --><font class="lisp">setq</font><!-- open: 187, close: 187 --> <!-- MATCHED MATCHED MATCHED -->'ing special variables
to the extra values.

In the normal case, multiple values are not used.  Special syntax is
required both to <!-- open: 188, close: 187 --><font class="italic">produce</font><!-- open: 188, close: 188 --> <!-- MATCHED MATCHED MATCHED --> multiple values and to <!-- open: 189, close: 188 --><font class="italic">receive</font><!-- open: 189, close: 189 --> <!-- MATCHED MATCHED MATCHED --> them.
If the caller does not receive multiple values, the first of the
multiple values will be received as the ordinary value.

The primitive for producing multiple values is <!-- open: 190, close: 189 --><font class="lisp">return</font><!-- open: 190, close: 190 --> <!-- MATCHED MATCHED MATCHED -->, which when
given more than one argument returns all its arguments as the values of
the <!-- open: 191, close: 190 --><font class="lisp">prog</font><!-- open: 191, close: 191 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 192, close: 191 --><font class="lisp">do</font><!-- open: 192, close: 192 --> <!-- MATCHED MATCHED MATCHED --> from which it is returning.  The variant
<!-- open: 193, close: 192 --><font class="lisp">return-from</font><!-- open: 193, close: 193 --> <!-- MATCHED MATCHED MATCHED --> also can produce multiple values.  Many system functions
produce multiple values, but they all do it via the <!-- open: 194, close: 193 --><font class="lisp">return</font><!-- open: 194, close: 194 --> <!-- MATCHED MATCHED MATCHED --> primitive.
<!-- This could be phrased better. ******* -->

The special forms for receiving multiple values are <!-- open: 195, close: 194 --><font class="lisp">multiple-value</font><!-- open: 195, close: 195 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 196, close: 195 --><font class="lisp">multiple-value-list</font><!-- open: 196, close: 196 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 197, close: 196 --><font class="lisp">multiple-value-bind</font><!-- open: 197, close: 197 --> <!-- MATCHED MATCHED MATCHED -->.  These include
a form and an indication of where to put the values returned by that form.

<div class='defspec' id='multiple-value'><font class='exdent'><font class='funcname' id='multiple-value'>multiple-value</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 198, close: 197 --><font class="lisp">(multiple-value <!-- open: 199, close: 197 --><font class="italic">var-list</font><!-- open: 199, close: 198 --> <!-- open: 200, close: 198 --><font class="italic">form</font><!-- open: 200, close: 199 -->)</font><!-- open: 200, close: 200 --> <!-- MATCHED MATCHED MATCHED --> is a special
form used for calling a function which
is expected to return more than one value.
<p class='cindent'><!-- "multiple value" -->
<p class='cindent'><!-- returning multiple values -->
<!-- open: 201, close: 200 --><font class="italic">var-list</font><!-- open: 201, close: 201 --> <!-- MATCHED MATCHED MATCHED --> should be a list of variables.
<!-- open: 202, close: 201 --><font class="italic">form</font><!-- open: 202, close: 202 --> <!-- MATCHED MATCHED MATCHED --> is evaluated, and the variables in <!-- open: 203, close: 202 --><font class="italic">var-list</font><!-- open: 203, close: 203 --> <!-- MATCHED MATCHED MATCHED -->
will be <!-- open: 204, close: 203 --><font class="italic">set</font><!-- open: 204, close: 204 --> <!-- MATCHED MATCHED MATCHED --> (not lambda-bound) to the values returned by <!-- open: 205, close: 204 --><font class="italic">form</font><!-- open: 205, close: 205 --> <!-- MATCHED MATCHED MATCHED -->.  If more values
are returned than there are variables in <!-- open: 206, close: 205 --><font class="italic">var-list</font><!-- open: 206, close: 206 --> <!-- MATCHED MATCHED MATCHED -->, then the extra values
are ignored.  If there are more variables than values returned,
extra values of <!-- open: 207, close: 206 --><font class="lisp">nil</font><!-- open: 207, close: 207 --> <!-- MATCHED MATCHED MATCHED --> are supplied.  It is allowed to have <!-- open: 208, close: 207 --><font class="lisp">nil</font><!-- open: 208, close: 208 --> <!-- MATCHED MATCHED MATCHED -->
in the <!-- open: 209, close: 208 --><font class="italic">var-list</font><!-- open: 209, close: 209 --> <!-- MATCHED MATCHED MATCHED -->, which means that the corresponding value is to be
ignored (you can't use <!-- open: 210, close: 209 --><font class="lisp">nil</font><!-- open: 210, close: 210 --> <!-- MATCHED MATCHED MATCHED --> as a variable.)
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(multiple-value (symbol already-there-p)
	(intern "goo"))
</pre>
<!-- open: 211, close: 210 --><font class="lisp">intern</font><!-- open: 211, close: 211 --> <!-- MATCHED MATCHED MATCHED --> returns a second value, which is <!-- open: 212, close: 211 --><font class="lisp">t</font><!-- open: 212, close: 212 --> <!-- MATCHED MATCHED MATCHED --> if the symbol returned as the
first value was already on the obarray, or else <!-- open: 213, close: 212 --><font class="lisp">nil</font><!-- open: 213, close: 213 --> <!-- MATCHED MATCHED MATCHED --> if it just put it there.
So if the symbol <!-- open: 214, close: 213 --><font class="lisp">goo</font><!-- open: 214, close: 214 --> <!-- MATCHED MATCHED MATCHED --> was already on the obarray, the variable <!-- open: 215, close: 214 --><font class="lisp">already-there-p</font><!-- open: 215, close: 215 --> <!-- MATCHED MATCHED MATCHED -->
will be set to <!-- open: 216, close: 215 --><font class="lisp">t</font><!-- open: 216, close: 216 --> <!-- MATCHED MATCHED MATCHED -->, else it will be set to <!-- open: 217, close: 216 --><font class="lisp">nil</font><!-- open: 217, close: 217 --> <!-- MATCHED MATCHED MATCHED -->.

<!-- open: 218, close: 217 --><font class="lisp">multiple-value</font><!-- open: 218, close: 218 --> <!-- MATCHED MATCHED MATCHED --> is usually used for effect rather than for value, however
its value is defined to be the first of the values returned by <!-- open: 219, close: 218 --><font class="italic">form</font><!-- open: 219, close: 219 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defspec' id='multiple-value-bind'><font class='exdent'><font class='funcname' id='multiple-value-bind'>multiple-value-bind</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->This is similar to <!-- open: 220, close: 219 --><font class="lisp">multiple-value</font><!-- open: 220, close: 220 --> <!-- MATCHED MATCHED MATCHED -->, but locally binds the variables which
receive the values, rather than <!-- open: 221, close: 220 --><font class="lisp">setq</font><!-- open: 221, close: 221 --> <!-- MATCHED MATCHED MATCHED -->ing them.  The form looks like:
<pre class='lisp'>
(multiple-value-bind (<!-- open: 222, close: 221 --><font class="italic">var1 var2...</font><!-- open: 222, close: 222 --> <!-- MATCHED MATCHED MATCHED -->)
     (<!-- open: 223, close: 222 --><font class="italic">function</font><!-- open: 223, close: 223 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 224, close: 223 --><font class="italic">args...</font><!-- open: 224, close: 224 --> <!-- MATCHED MATCHED MATCHED -->)
  <!-- open: 225, close: 224 --><font class="italic">body...</font><!-- open: 225, close: 225 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
The scope of the binding of <!-- open: 226, close: 225 --><font class="italic">var1</font><!-- open: 226, close: 226 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 227, close: 226 --><font class="italic">var2</font><!-- open: 227, close: 227 --> <!-- MATCHED MATCHED MATCHED -->, etc. is <!-- open: 228, close: 227 --><font class="italic">body</font><!-- open: 228, close: 228 --> <!-- MATCHED MATCHED MATCHED -->; they are
not bound until after the function call.
</div>

<div class='defspec' id='multiple-value-list'><font class='exdent'><font class='funcname' id='multiple-value-list'>multiple-value-list</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 229, close: 228 --><font class="lisp">(multiple-value-list <!-- open: 230, close: 228 --><font class="italic">form</font><!-- open: 230, close: 229 -->)</font><!-- open: 230, close: 230 --> <!-- MATCHED MATCHED MATCHED --> evaluates <!-- open: 231, close: 230 --><font class="italic">form</font><!-- open: 231, close: 231 --> <!-- MATCHED MATCHED MATCHED -->, and returns a list of
the values it returned.  This is useful for when you don't know how many values
to expect.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(setq a (multiple-value-list (intern "goo")))
a =&gt; (goo nil #&lt;Package User&gt;)
</pre>
This is similar to the example of <!-- open: 232, close: 231 --><font class="lisp">multiple-value</font><!-- open: 232, close: 232 --> <!-- MATCHED MATCHED MATCHED --> above; <!-- open: 233, close: 232 --><font class="lisp">a</font><!-- open: 233, close: 233 --> <!-- MATCHED MATCHED MATCHED --> will be set
to a list of three elements, the three values returned by <!-- open: 234, close: 233 --><font class="lisp">intern</font><!-- open: 234, close: 234 --> <!-- MATCHED MATCHED MATCHED -->.
The first is the newly interned symbol <!-- open: 235, close: 234 --><font class="lisp">goo</font><!-- open: 235, close: 235 --> <!-- MATCHED MATCHED MATCHED -->, the second is 
<!-- open: 236, close: 235 --><font class="lisp">nil</font><!-- open: 236, close: 236 --> <!-- MATCHED MATCHED MATCHED --> to indicate that it is newly-interned, and the third is
the package on which it was interned.
</div>

Due to the syntactic structure of Lisp, it is often the case that the value
of a certain form is the value of a sub-form of it.  For example, the
value of a <!-- open: 237, close: 236 --><font class="lisp">cond</font><!-- open: 237, close: 237 --> <!-- MATCHED MATCHED MATCHED --> is the value of the last form in the selected clause.
In most such cases, if the sub-form produces multiple values, the original
form will also produce all of those values.  This <!-- open: 238, close: 237 --><font class="italic">passing-back</font><!-- open: 238, close: 238 --> <!-- MATCHED MATCHED MATCHED --> of
multiple values of course has no effect unless eventually one of the
special forms for receiving multiple values is reached.
The exact rule governing passing-back of multiple values is as follows:

If <!-- open: 239, close: 238 --><font class="italic">X</font><!-- open: 239, close: 239 --> <!-- MATCHED MATCHED MATCHED --> is a form, and <!-- open: 240, close: 239 --><font class="italic">Y</font><!-- open: 240, close: 240 --> <!-- MATCHED MATCHED MATCHED --> is a sub-form of <!-- open: 241, close: 240 --><font class="italic">X</font><!-- open: 241, close: 241 --> <!-- MATCHED MATCHED MATCHED -->, then if the value
of <!-- open: 242, close: 241 --><font class="italic">Y</font><!-- open: 242, close: 242 --> <!-- MATCHED MATCHED MATCHED --> is unconditionally returned as the value of <!-- open: 243, close: 242 --><font class="italic">X</font><!-- open: 243, close: 243 --> <!-- MATCHED MATCHED MATCHED -->, with no
intervening computation, then all the multiple values returned by <!-- open: 244, close: 243 --><font class="italic">Y</font><!-- open: 244, close: 244 --> <!-- MATCHED MATCHED MATCHED -->
are returned by <!-- open: 245, close: 244 --><font class="italic">X</font><!-- open: 245, close: 245 --> <!-- MATCHED MATCHED MATCHED -->.  In all other cases, multiple values or only
single values may be returned at the discretion of the implementation;
users should not depend on this.  The reason we don't guarantee
non-transmission of multiple values is because such a guarantee would
not be very useful and the efficiency cost of enforcing it would be
high.  Even <!-- open: 246, close: 245 --><font class="lisp">setq</font><!-- open: 246, close: 246 --> <!-- MATCHED MATCHED MATCHED -->'ing a variable to the result of a form, then
returning the value of that variable might be made to pass multiple
values by an optimizing compiler which realized that the <!-- open: 247, close: 246 --><font class="lisp">setq</font><!-- open: 247, close: 247 --> <!-- MATCHED MATCHED MATCHED -->ing of
the variable was unnecessary.

Note that use of a form as an argument to a function never passes-back
multiple values.  We choose not to generate several separate arguments
from the several values, because this would make the source code
obscure; it would not be syntactically obvious that a single form does
not coorrespond to a single argument.  Instead the first value of a
form is used as the argument and the remaining values are discarded.
Passing-back of multiple values happens only with special forms.
For clarity, the interaction of several common special forms with
multiple values is described.  This can all be deduced from the rule
given above.

The body of a <!-- open: 248, close: 247 --><font class="lisp">defun</font><!-- open: 248, close: 248 --> <!-- MATCHED MATCHED MATCHED --> or a <!-- open: 249, close: 248 --><font class="lisp">lambda</font><!-- open: 249, close: 249 --> <!-- MATCHED MATCHED MATCHED -->, and variations such as the
body of a function, the body of a <!-- open: 250, close: 249 --><font class="lisp">let</font><!-- open: 250, close: 250 --> <!-- MATCHED MATCHED MATCHED -->, etc. pass back multiple
values from the last form in the body.

<!-- open: 251, close: 250 --><font class="lisp">eval</font><!-- open: 251, close: 251 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 252, close: 251 --><font class="lisp">apply</font><!-- open: 252, close: 252 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 253, close: 252 --><font class="lisp">funcall</font><!-- open: 253, close: 253 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 254, close: 253 --><font class="lisp">lexpr-funcall</font><!-- open: 254, close: 254 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 255, close: 254 --><font class="lisp">&lt;-</font><!-- open: 255, close: 255 --> <!-- MATCHED MATCHED MATCHED -->
pass back multiple values from the function called.

<!-- open: 256, close: 255 --><font class="lisp">progn</font><!-- open: 256, close: 256 --> <!-- MATCHED MATCHED MATCHED --> passes back multiple values from its last form.
<!-- open: 257, close: 256 --><font class="lisp">progv</font><!-- open: 257, close: 257 --> <!-- MATCHED MATCHED MATCHED --> does so also.
<!-- open: 258, close: 257 --><font class="lisp">prog1</font><!-- open: 258, close: 258 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 259, close: 258 --><font class="lisp">prog2</font><!-- open: 259, close: 259 --> <!-- MATCHED MATCHED MATCHED --> however do not pass back multiple values.

<!-- open: 260, close: 259 --><font class="lisp">and</font><!-- open: 260, close: 260 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 261, close: 260 --><font class="lisp">or</font><!-- open: 261, close: 261 --> <!-- MATCHED MATCHED MATCHED --> pass back multiple values from their last form,
but not from previous forms since the return is conditional.

<!-- open: 262, close: 261 --><font class="lisp">cond</font><!-- open: 262, close: 262 --> <!-- MATCHED MATCHED MATCHED --> passes back multiple values from the last form in the
selected clause, but not if the clause is only one long (i.e. the
returned value is the value of the predicate) since the return is
conditional.  This applies even to the last clause where the return
is not really conditional (the implementation is allowed to pass
or not to pass multiple values in this case).

The variants of <!-- open: 263, close: 262 --><font class="lisp">cond</font><!-- open: 263, close: 263 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 264, close: 263 --><font class="lisp">if</font><!-- open: 264, close: 264 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 265, close: 264 --><font class="lisp">select</font><!-- open: 265, close: 265 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 266, close: 265 --><font class="lisp">selectq</font><!-- open: 266, close: 266 --> <!-- MATCHED MATCHED MATCHED -->, and
<!-- open: 267, close: 266 --><font class="lisp">dispatch</font><!-- open: 267, close: 267 --> <!-- MATCHED MATCHED MATCHED --> pass back multiple values.

<!-- open: 268, close: 267 --><font class="lisp">prog</font><!-- open: 268, close: 268 --> <!-- MATCHED MATCHED MATCHED --> passes back the number of values given as arguments to
the <!-- open: 269, close: 268 --><font class="lisp">return</font><!-- open: 269, close: 269 --> <!-- MATCHED MATCHED MATCHED --> that returns from it.  <!-- open: 270, close: 269 --><font class="lisp">(return <!-- open: 271, close: 269 --><font class="italic">form</font><!-- open: 271, close: 270 -->)</font><!-- open: 271, close: 271 --> <!-- MATCHED MATCHED MATCHED -->
may return 1 value or may return all the values of <!-- open: 272, close: 271 --><font class="italic">form</font><!-- open: 272, close: 272 --> <!-- MATCHED MATCHED MATCHED -->; as always
the implementation is not constrained not to return extra values.
<!-- open: 273, close: 272 --><font class="lisp">(multiple-value-return <!-- open: 274, close: 272 --><font class="italic">form</font><!-- open: 274, close: 273 -->)</font><!-- open: 274, close: 274 --> <!-- MATCHED MATCHED MATCHED --> returns from a <!-- open: 275, close: 274 --><font class="lisp">prog</font><!-- open: 275, close: 275 --> <!-- MATCHED MATCHED MATCHED -->,
passing back all the values of <!-- open: 276, close: 275 --><font class="italic">form</font><!-- open: 276, close: 276 --> <!-- MATCHED MATCHED MATCHED -->.

<!-- open: 277, close: 276 --><font class="lisp">do</font><!-- open: 277, close: 277 --> <!-- MATCHED MATCHED MATCHED --> behaves like <!-- open: 278, close: 277 --><font class="lisp">prog</font><!-- open: 278, close: 278 --> <!-- MATCHED MATCHED MATCHED --> with respect to <!-- open: 279, close: 278 --><font class="lisp">return</font><!-- open: 279, close: 279 --> <!-- MATCHED MATCHED MATCHED -->.
All the values of the last <!-- open: 280, close: 279 --><font class="italic">exit-form</font><!-- open: 280, close: 280 --> <!-- MATCHED MATCHED MATCHED --> are returned.
[This is the "right" thing unless you think of the implementation
in terms of <!-- open: 281, close: 280 --><font class="lisp">return</font><!-- open: 281, close: 281 --> <!-- MATCHED MATCHED MATCHED -->; what should we do?] *******

<!-- open: 282, close: 281 --><font class="lisp">unwind-protect</font><!-- open: 282, close: 282 --> <!-- MATCHED MATCHED MATCHED --> does <!-- open: 283, close: 282 --><font class="italic">not</font><!-- open: 283, close: 283 --> <!-- MATCHED MATCHED MATCHED --> pass back multiple values.
It clearly should, however this is currently difficult to implement.
This should be fixed later. *******

<div class='section' id='5.3'>5.3 Evalhook</div>
<div class='defvar' id='evalhook'><font class='exdent'><font class='funcname' id='evalhook'>evalhook</font><font class="italic"> Variable</font><br></font><!-- end font_exdent -->If the value of <!-- open: 284, close: 283 --><font class="lisp">evalhook</font><!-- open: 284, close: 284 --> <!-- MATCHED MATCHED MATCHED --> is non-<!-- open: 285, close: 284 --><font class="lisp">nil</font><!-- open: 285, close: 285 --> <!-- MATCHED MATCHED MATCHED -->, then special things
happen in the evaluator.  When a form (even an atom) is to be evaluated,
<!-- open: 286, close: 285 --><font class="lisp">evalhook</font><!-- open: 286, close: 286 --> <!-- MATCHED MATCHED MATCHED --> is bound to <!-- open: 287, close: 286 --><font class="lisp">nil</font><!-- open: 287, close: 287 --> <!-- MATCHED MATCHED MATCHED --> and the function which
was <!-- open: 288, close: 287 --><font class="lisp">evalhook</font><!-- open: 288, close: 288 --> <!-- MATCHED MATCHED MATCHED -->'s value is applied to one argument--the form that was trying
to be evaluated.  The value it returns is then returned from the evaluator.
This feature is used by the <!-- open: 289, close: 288 --><font class="lisp">step</font><!-- open: 289, close: 289 --> <!-- MATCHED MATCHED MATCHED --> program (see <font color='red'>LINK:(</font>step-fun)).
</div>

<!-- open: 290, close: 289 --><font class="lisp">evalhook</font><!-- open: 290, close: 290 --> <!-- MATCHED MATCHED MATCHED --> is bound to <!-- open: 291, close: 290 --><font class="lisp">nil</font><!-- open: 291, close: 291 --> <!-- MATCHED MATCHED MATCHED --> by <!-- open: 292, close: 291 --><font class="lisp">break</font><!-- open: 292, close: 292 --> <!-- MATCHED MATCHED MATCHED --> and by
the error handler,
and <!-- open: 293, close: 292 --><font class="lisp">setq</font><!-- open: 293, close: 293 --> <!-- MATCHED MATCHED MATCHED -->'ed
to <!-- open: 294, close: 293 --><font class="lisp">nil</font><!-- open: 294, close: 294 --> <!-- MATCHED MATCHED MATCHED --> by errors that go back to top level and print <!-- open: 295, close: 294 --><font class="lisp">*</font><!-- open: 295, close: 295 --> <!-- MATCHED MATCHED MATCHED -->.
This provides the ability to escape from this mode if something bad
happens.

In order not to impair the efficiency of the Lisp interpreter,
several restrictions are imposed on <!-- open: 296, close: 295 --><font class="lisp">evalhook</font><!-- open: 296, close: 296 --> <!-- MATCHED MATCHED MATCHED -->.
It only applies to evaluation -- whether in a read-eval-print loop,
internally in evaluating arguments in forms, or by explicit use
of the function <!-- open: 297, close: 296 --><font class="lisp">eval</font><!-- open: 297, close: 297 --> <!-- MATCHED MATCHED MATCHED -->.  It <!-- open: 298, close: 297 --><font class="italic">does not</font><!-- open: 298, close: 298 --> <!-- MATCHED MATCHED MATCHED --> have any effect
on compiled function references, on use of the function <!-- open: 299, close: 298 --><font class="lisp">apply</font><!-- open: 299, close: 299 --> <!-- MATCHED MATCHED MATCHED -->,
or on the "mapping" functions.
(On the Lisp Machine, as opposed to Maclisp, it is not
necessary to do <!-- open: 300, close: 299 --><font class="lisp">(*rset t)</font><!-- open: 300, close: 300 --> <!-- MATCHED MATCHED MATCHED --> nor <!-- open: 301, close: 300 --><font class="lisp">(sstatus evalhook t)</font><!-- open: 301, close: 301 --> <!-- MATCHED MATCHED MATCHED -->.)
<!-- This is from the Maclisp manual, in case we ever support this feature. -->
<!-- Also, as a special case, the array reference which is the first -->
<!-- argument to <!-- open: 302, close: 301 --><font class="lisp">store</font><!-- open: 302, close: 302 --> <!-- MATCHED MATCHED MATCHED --> is never seen by the <!-- open: 303, close: 302 --><font class="lisp">evalhook</font><!-- open: 303, close: 303 --> <!-- MATCHED MATCHED MATCHED --> function; -->
<!-- however, the subexpressions of the array reference (the indices) will -->
<!-- be seen.  (This special treatment avoids a problem with the way <!-- open: 304, close: 303 --><font class="lisp">store</font><!-- open: 304, close: 304 --> <!-- MATCHED MATCHED MATCHED --> -->
<!-- works.) -->
(Also, Maclisp's special-case check for <!-- open: 305, close: 304 --><font class="lisp">store</font><!-- open: 305, close: 305 --> <!-- MATCHED MATCHED MATCHED --> is not implemented.)

<div class='defun' id='evalhook'>
  <font class='exdent'>
    <font class='funcname'>evalhook </font>
    <font class='italic' color='purple'>form hook</font>
  </font><br>
<!-- open: 306, close: 305 --><font class="lisp">evalhook</font><!-- open: 306, close: 306 --> <!-- MATCHED MATCHED MATCHED --> is a function which helps
exploit the <!-- open: 307, close: 306 --><font class="lisp">evalhook</font><!-- open: 307, close: 307 --> <!-- MATCHED MATCHED MATCHED --> feature.  The <!-- open: 308, close: 307 --><font class="italic">form</font><!-- open: 308, close: 308 --> <!-- MATCHED MATCHED MATCHED --> is evaluated
with <!-- open: 309, close: 308 --><font class="lisp">evalhook</font><!-- open: 309, close: 309 --> <!-- MATCHED MATCHED MATCHED --> lambda-bound to the functional form <!-- open: 310, close: 309 --><font class="lisp">hook</font><!-- open: 310, close: 310 --> <!-- MATCHED MATCHED MATCHED -->.
The checking of <!-- open: 311, close: 310 --><font class="lisp">evalhook</font><!-- open: 311, close: 311 --> <!-- MATCHED MATCHED MATCHED --> is bypassed in the evaluation
of <!-- open: 312, close: 311 --><font class="italic">form</font><!-- open: 312, close: 312 --> <!-- MATCHED MATCHED MATCHED --> itself, but not in any subsidiary evaluations,
for instance of arguments in the <!-- open: 313, close: 312 --><font class="italic">form</font><!-- open: 313, close: 313 --> <!-- MATCHED MATCHED MATCHED -->.
This is like a "one-instruction proceed" in a machine-language
debugger.  
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent --><!-- open: 314, close: 313 --><font class="main">;; This function evaluates a form while printing debugging information.</font><!-- open: 314, close: 314 --> <!-- MATCHED MATCHED MATCHED -->
(defun hook (x)
   (terpri)
   (evalhook x 'hook-function))

<!-- open: 315, close: 314 --><font class="main">;; Notice how this function calls <!-- open: 316, close: 314 --><font class="lisp">evalhook</font><!-- open: 316, close: 315 --> to evaluate the form <!-- open: 317, close: 315 --><font class="lisp">f</font><!-- open: 317, close: 316 -->,</font><!-- open: 317, close: 317 --> <!-- MATCHED MATCHED MATCHED -->
<!-- open: 318, close: 317 --><font class="main">;; so as to hook the sub-forms.</font><!-- open: 318, close: 318 --> <!-- MATCHED MATCHED MATCHED -->
(defun hook-function (f)
   (let ((v (evalhook f 'hook-function)))
     (format t "form: ~s~%value: ~s~%" f v)
     v))
</pre>

The following output might be seen from <!-- open: 319, close: 318 --><font class="lisp">(hook '(cons (car '(a . b)) 'c))</font><!-- open: 319, close: 319 --> <!-- MATCHED MATCHED MATCHED -->:
<pre class='lisp'>
form: (cons (car (quote (a . b))) (quote c))
form: (car (quote (a . b)))
form: (quote (a . b))
value: (a . b)
value: a
form: (quote c)
value: c
value: (a . c)

(a . c)
</pre>
</div>
<!-- eof -->
</body>
</html>

